From 130bd5937ccb098450bafc7e8ed63c58f188d6fb Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 2 Jul 2020 13:01:48 -0400 Subject: [PATCH] docs: Add guidance about list model performance Add a section about the performance tradeoffs between different list model implementations. --- docs/reference/gtk/section-list-widget.md | 26 +++++++++++++++++++++++ gtk/gtkstringlist.c | 3 +++ 2 files changed, 29 insertions(+) diff --git a/docs/reference/gtk/section-list-widget.md b/docs/reference/gtk/section-list-widget.md index 86033cdbf0..e91576b3ec 100644 --- a/docs/reference/gtk/section-list-widget.md +++ b/docs/reference/gtk/section-list-widget.md @@ -123,6 +123,32 @@ the number of listitems they create such as with gtk_grid_view_set_max_columns() and developers running into performance problems should definitely study the tradeoffs of those and experiment with them. +## Choosing the right model {#model-choosing} + +GTK offers a wide variety of wrapping models which change or supplement an +existing model (or models) in some way. But when it comes to storing your +actual data, there are only a few ready-made choices available: #GListStore +and #GtkStringList. + +GListStore is backed by a balanced tree and has performance characteristics +that are expected for that data structure. It works reasonably well for dataset +sizes in the 1,000,000 range, and can handle insertions and deletions. It uses +a cached iter to make linear access to the items fast. + +GtkStringList is not a general store - it can only handle strings. It is +backed by an dynamically allocated array and has performance characteristics +that are expected for that data structure. GtkStringList is a good fit for any +place where you would otherwise use `char*[]` and works best if the dataset +is not very dynamic. + +If these models don't fit your use case or scalability requirements, you +should make a custom #GListModel. It is a small interface and not very hard +to implement. + +For asymptotic performance comparisons between tree- and array-based +implementations, see this +[article](https://en.wikipedia.org/wiki/Dynamic_array#Performance). + ## Displaying trees {#displaying-trees} While #GtkTreeView provided built-in support for trees, the list widgets, and diff --git a/gtk/gtkstringlist.c b/gtk/gtkstringlist.c index d4f90c6781..c7383536f5 100644 --- a/gtk/gtkstringlist.c +++ b/gtk/gtkstringlist.c @@ -36,6 +36,9 @@ * * The objects in the model have a "string" property. * + * GtkStringList is well-suited for any place where you would + * typically use a `char*[]`, but need a list model. + * * # GtkStringList as GtkBuildable * * The GtkStringList implementation of the GtkBuildable interface -- 2.30.2